<!DOCTYPE html>
<html>
  <head>
      <meta charset="utf-8" />
      <title>Combined-User-Install-Guide</title>
      <style>.markdown-preview:not([data-use-github-style]) { padding: 2em; font-size: 1.2em; color: rgb(85, 85, 85); overflow: auto; background-color: rgb(255, 255, 255); }
.markdown-preview:not([data-use-github-style]) > :first-child { margin-top: 0px; }
.markdown-preview:not([data-use-github-style]) h1, .markdown-preview:not([data-use-github-style]) h2, .markdown-preview:not([data-use-github-style]) h3, .markdown-preview:not([data-use-github-style]) h4, .markdown-preview:not([data-use-github-style]) h5, .markdown-preview:not([data-use-github-style]) h6 { line-height: 1.2; margin-top: 1.5em; margin-bottom: 0.5em; color: rgb(3, 3, 3); }
.markdown-preview:not([data-use-github-style]) h1 { font-size: 2.4em; font-weight: 300; }
.markdown-preview:not([data-use-github-style]) h2 { font-size: 1.8em; font-weight: 400; }
.markdown-preview:not([data-use-github-style]) h3 { font-size: 1.5em; font-weight: 500; }
.markdown-preview:not([data-use-github-style]) h4 { font-size: 1.2em; font-weight: 600; }
.markdown-preview:not([data-use-github-style]) h5 { font-size: 1.1em; font-weight: 600; }
.markdown-preview:not([data-use-github-style]) h6 { font-size: 1em; font-weight: 600; }
.markdown-preview:not([data-use-github-style]) strong { color: rgb(3, 3, 3); }
.markdown-preview:not([data-use-github-style]) del { color: rgb(126, 126, 126); }
.markdown-preview:not([data-use-github-style]) a, .markdown-preview:not([data-use-github-style]) a code { color: rgb(0, 0, 0); }
.markdown-preview:not([data-use-github-style]) img { max-width: 100%; }
.markdown-preview:not([data-use-github-style]) > p { margin-top: 0px; margin-bottom: 1.5em; }
.markdown-preview:not([data-use-github-style]) > ul, .markdown-preview:not([data-use-github-style]) > ol { margin-bottom: 1.5em; }
.markdown-preview:not([data-use-github-style]) blockquote { margin: 1.5em 0px; font-size: inherit; color: rgb(126, 126, 126); border-color: rgb(214, 214, 214); border-width: 4px; }
.markdown-preview:not([data-use-github-style]) hr { margin: 3em 0px; border-top-width: 2px; border-top-style: dashed; border-top-color: rgb(214, 214, 214); background: none; }
.markdown-preview:not([data-use-github-style]) table { margin: 1.5em 0px; }
.markdown-preview:not([data-use-github-style]) th { color: rgb(3, 3, 3); }
.markdown-preview:not([data-use-github-style]) th, .markdown-preview:not([data-use-github-style]) td { padding: 0.66em 1em; border: 1px solid rgb(214, 214, 214); }
.markdown-preview:not([data-use-github-style]) code { color: rgb(3, 3, 3); background-color: rgb(240, 240, 240); }
.markdown-preview:not([data-use-github-style]) pre.editor-colors { margin: 1.5em 0px; padding: 1em; font-size: 0.92em; border-radius: 3px; background-color: rgb(245, 245, 245); }
.markdown-preview:not([data-use-github-style]) kbd { color: rgb(3, 3, 3); border-width: 1px 1px 2px; border-style: solid; border-color: rgb(214, 214, 214) rgb(214, 214, 214) rgb(199, 199, 199); background-color: rgb(240, 240, 240); }
.markdown-preview[data-use-github-style] { font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif; line-height: 1.6; word-wrap: break-word; padding: 30px; font-size: 16px; color: rgb(51, 51, 51); overflow: scroll; background-color: rgb(255, 255, 255); }
.markdown-preview[data-use-github-style] > :first-child { margin-top: 0px !important; }
.markdown-preview[data-use-github-style] > :last-child { margin-bottom: 0px !important; }
.markdown-preview[data-use-github-style] a:not([href]) { color: inherit; text-decoration: none; }
.markdown-preview[data-use-github-style] .absent { color: rgb(204, 0, 0); }
.markdown-preview[data-use-github-style] .anchor { position: absolute; top: 0px; left: 0px; display: block; padding-right: 6px; padding-left: 30px; margin-left: -30px; }
.markdown-preview[data-use-github-style] .anchor:focus { outline: none; }
.markdown-preview[data-use-github-style] h1, .markdown-preview[data-use-github-style] h2, .markdown-preview[data-use-github-style] h3, .markdown-preview[data-use-github-style] h4, .markdown-preview[data-use-github-style] h5, .markdown-preview[data-use-github-style] h6 { position: relative; margin-top: 1em; margin-bottom: 16px; font-weight: bold; line-height: 1.4; }
.markdown-preview[data-use-github-style] h1 .octicon-link, .markdown-preview[data-use-github-style] h2 .octicon-link, .markdown-preview[data-use-github-style] h3 .octicon-link, .markdown-preview[data-use-github-style] h4 .octicon-link, .markdown-preview[data-use-github-style] h5 .octicon-link, .markdown-preview[data-use-github-style] h6 .octicon-link { display: none; color: rgb(0, 0, 0); vertical-align: middle; }
.markdown-preview[data-use-github-style] h1:hover .anchor, .markdown-preview[data-use-github-style] h2:hover .anchor, .markdown-preview[data-use-github-style] h3:hover .anchor, .markdown-preview[data-use-github-style] h4:hover .anchor, .markdown-preview[data-use-github-style] h5:hover .anchor, .markdown-preview[data-use-github-style] h6:hover .anchor { padding-left: 8px; margin-left: -30px; text-decoration: none; }
.markdown-preview[data-use-github-style] h1:hover .anchor .octicon-link, .markdown-preview[data-use-github-style] h2:hover .anchor .octicon-link, .markdown-preview[data-use-github-style] h3:hover .anchor .octicon-link, .markdown-preview[data-use-github-style] h4:hover .anchor .octicon-link, .markdown-preview[data-use-github-style] h5:hover .anchor .octicon-link, .markdown-preview[data-use-github-style] h6:hover .anchor .octicon-link { display: inline-block; }
.markdown-preview[data-use-github-style] h1 tt, .markdown-preview[data-use-github-style] h2 tt, .markdown-preview[data-use-github-style] h3 tt, .markdown-preview[data-use-github-style] h4 tt, .markdown-preview[data-use-github-style] h5 tt, .markdown-preview[data-use-github-style] h6 tt, .markdown-preview[data-use-github-style] h1 code, .markdown-preview[data-use-github-style] h2 code, .markdown-preview[data-use-github-style] h3 code, .markdown-preview[data-use-github-style] h4 code, .markdown-preview[data-use-github-style] h5 code, .markdown-preview[data-use-github-style] h6 code { font-size: inherit; }
.markdown-preview[data-use-github-style] h1 { padding-bottom: 0.3em; font-size: 2.25em; line-height: 1.2; border-bottom-width: 1px; border-bottom-style: solid; border-bottom-color: rgb(238, 238, 238); }
.markdown-preview[data-use-github-style] h1 .anchor { line-height: 1; }
.markdown-preview[data-use-github-style] h2 { padding-bottom: 0.3em; font-size: 1.75em; line-height: 1.225; border-bottom-width: 1px; border-bottom-style: solid; border-bottom-color: rgb(238, 238, 238); }
.markdown-preview[data-use-github-style] h2 .anchor { line-height: 1; }
.markdown-preview[data-use-github-style] h3 { font-size: 1.5em; line-height: 1.43; }
.markdown-preview[data-use-github-style] h3 .anchor { line-height: 1.2; }
.markdown-preview[data-use-github-style] h4 { font-size: 1.25em; }
.markdown-preview[data-use-github-style] h4 .anchor { line-height: 1.2; }
.markdown-preview[data-use-github-style] h5 { font-size: 1em; }
.markdown-preview[data-use-github-style] h5 .anchor { line-height: 1.1; }
.markdown-preview[data-use-github-style] h6 { font-size: 1em; color: rgb(119, 119, 119); }
.markdown-preview[data-use-github-style] h6 .anchor { line-height: 1.1; }
.markdown-preview[data-use-github-style] p, .markdown-preview[data-use-github-style] blockquote, .markdown-preview[data-use-github-style] ul, .markdown-preview[data-use-github-style] ol, .markdown-preview[data-use-github-style] dl, .markdown-preview[data-use-github-style] table, .markdown-preview[data-use-github-style] pre { margin-top: 0px; margin-bottom: 16px; }
.markdown-preview[data-use-github-style] hr { height: 4px; padding: 0px; margin: 16px 0px; border: 0px none; background-color: rgb(231, 231, 231); }
.markdown-preview[data-use-github-style] ul, .markdown-preview[data-use-github-style] ol { padding-left: 2em; }
.markdown-preview[data-use-github-style] ul.no-list, .markdown-preview[data-use-github-style] ol.no-list { padding: 0px; list-style-type: none; }
.markdown-preview[data-use-github-style] ul ul, .markdown-preview[data-use-github-style] ul ol, .markdown-preview[data-use-github-style] ol ol, .markdown-preview[data-use-github-style] ol ul { margin-top: 0px; margin-bottom: 0px; }
.markdown-preview[data-use-github-style] li > p { margin-top: 16px; }
.markdown-preview[data-use-github-style] dl { padding: 0px; }
.markdown-preview[data-use-github-style] dl dt { padding: 0px; margin-top: 16px; font-size: 1em; font-style: italic; font-weight: bold; }
.markdown-preview[data-use-github-style] dl dd { padding: 0px 16px; margin-bottom: 16px; }
.markdown-preview[data-use-github-style] blockquote { padding: 0px 15px; color: rgb(119, 119, 119); border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); }
.markdown-preview[data-use-github-style] blockquote > :first-child { margin-top: 0px; }
.markdown-preview[data-use-github-style] blockquote > :last-child { margin-bottom: 0px; }
.markdown-preview[data-use-github-style] table { display: block; width: 100%; overflow: auto; word-break: keep-all; }
.markdown-preview[data-use-github-style] table th { font-weight: bold; }
.markdown-preview[data-use-github-style] table th, .markdown-preview[data-use-github-style] table td { padding: 6px 13px; border: 1px solid rgb(221, 221, 221); }
.markdown-preview[data-use-github-style] table tr { border-top-width: 1px; border-top-style: solid; border-top-color: rgb(204, 204, 204); background-color: rgb(255, 255, 255); }
.markdown-preview[data-use-github-style] table tr:nth-child(2n) { background-color: rgb(248, 248, 248); }
.markdown-preview[data-use-github-style] img { max-width: 100%; box-sizing: border-box; }
.markdown-preview[data-use-github-style] .emoji { max-width: none; }
.markdown-preview[data-use-github-style] span.frame { display: block; overflow: hidden; }
.markdown-preview[data-use-github-style] span.frame > span { display: block; float: left; width: auto; padding: 7px; margin: 13px 0px 0px; overflow: hidden; border: 1px solid rgb(221, 221, 221); }
.markdown-preview[data-use-github-style] span.frame span img { display: block; float: left; }
.markdown-preview[data-use-github-style] span.frame span span { display: block; padding: 5px 0px 0px; clear: both; color: rgb(51, 51, 51); }
.markdown-preview[data-use-github-style] span.align-center { display: block; overflow: hidden; clear: both; }
.markdown-preview[data-use-github-style] span.align-center > span { display: block; margin: 13px auto 0px; overflow: hidden; text-align: center; }
.markdown-preview[data-use-github-style] span.align-center span img { margin: 0px auto; text-align: center; }
.markdown-preview[data-use-github-style] span.align-right { display: block; overflow: hidden; clear: both; }
.markdown-preview[data-use-github-style] span.align-right > span { display: block; margin: 13px 0px 0px; overflow: hidden; text-align: right; }
.markdown-preview[data-use-github-style] span.align-right span img { margin: 0px; text-align: right; }
.markdown-preview[data-use-github-style] span.float-left { display: block; float: left; margin-right: 13px; overflow: hidden; }
.markdown-preview[data-use-github-style] span.float-left span { margin: 13px 0px 0px; }
.markdown-preview[data-use-github-style] span.float-right { display: block; float: right; margin-left: 13px; overflow: hidden; }
.markdown-preview[data-use-github-style] span.float-right > span { display: block; margin: 13px auto 0px; overflow: hidden; text-align: right; }
.markdown-preview[data-use-github-style] code, .markdown-preview[data-use-github-style] tt { padding: 0.2em 0px; margin: 0px; font-size: 85%; border-radius: 3px; background-color: rgba(0, 0, 0, 0.0392157); }
.markdown-preview[data-use-github-style] code::before, .markdown-preview[data-use-github-style] tt::before, .markdown-preview[data-use-github-style] code::after, .markdown-preview[data-use-github-style] tt::after { letter-spacing: -0.2em; content: " "; }
.markdown-preview[data-use-github-style] code br, .markdown-preview[data-use-github-style] tt br { display: none; }
.markdown-preview[data-use-github-style] del code { text-decoration: inherit; }
.markdown-preview[data-use-github-style] pre > code { padding: 0px; margin: 0px; font-size: 100%; word-break: normal; white-space: pre; border: 0px; background: transparent; }
.markdown-preview[data-use-github-style] .highlight { margin-bottom: 16px; }
.markdown-preview[data-use-github-style] .highlight pre, .markdown-preview[data-use-github-style] pre { padding: 16px; overflow: auto; font-size: 85%; line-height: 1.45; border-radius: 3px; background-color: rgb(247, 247, 247); }
.markdown-preview[data-use-github-style] .highlight pre { margin-bottom: 0px; word-break: normal; }
.markdown-preview[data-use-github-style] pre { word-wrap: normal; }
.markdown-preview[data-use-github-style] pre code, .markdown-preview[data-use-github-style] pre tt { display: inline; max-width: initial; padding: 0px; margin: 0px; overflow: initial; line-height: inherit; word-wrap: normal; border: 0px; background-color: transparent; }
.markdown-preview[data-use-github-style] pre code::before, .markdown-preview[data-use-github-style] pre tt::before, .markdown-preview[data-use-github-style] pre code::after, .markdown-preview[data-use-github-style] pre tt::after { content: normal; }
.markdown-preview[data-use-github-style] kbd { display: inline-block; padding: 3px 5px; font-size: 11px; line-height: 10px; color: rgb(85, 85, 85); vertical-align: middle; border-style: solid; border-width: 1px; border-color: rgb(204, 204, 204) rgb(204, 204, 204) rgb(187, 187, 187); border-radius: 3px; box-shadow: rgb(187, 187, 187) 0px -1px 0px inset; background-color: rgb(252, 252, 252); }
.markdown-preview[data-use-github-style] a { color: rgb(51, 122, 183); }
.markdown-preview[data-use-github-style] code { color: inherit; }
.markdown-preview[data-use-github-style] pre.editor-colors { padding: 0.8em 1em; margin-bottom: 1em; font-size: 0.85em; border-radius: 4px; overflow: auto; }
.scrollbars-visible-always .markdown-preview pre.editor-colors::shadow .vertical-scrollbar, .scrollbars-visible-always .markdown-preview pre.editor-colors::shadow .horizontal-scrollbar { visibility: hidden; }
.scrollbars-visible-always .markdown-preview pre.editor-colors:hover::shadow .vertical-scrollbar, .scrollbars-visible-always .markdown-preview pre.editor-colors:hover::shadow .horizontal-scrollbar { visibility: visible; }
.bracket-matcher .region {
  border-bottom: 1px dotted lime;
  position: absolute;
}

.spell-check-misspelling .region {
  border-bottom: 2px dotted rgba(255, 51, 51, 0.75);
}

pre.editor-colors,
.host {
  background-color: #ffffff;
  color: #555555;
}
pre.editor-colors .invisible-character,
.host .invisible-character {
  color: rgba(85, 85, 85, 0.2);
}
pre.editor-colors .indent-guide,
.host .indent-guide {
  color: rgba(85, 85, 85, 0.2);
}
pre.editor-colors .wrap-guide,
.host .wrap-guide {
  background-color: rgba(85, 85, 85, 0.2);
}
pre.editor-colors .gutter,
.host .gutter {
  color: #555555;
  background: #ffffff;
}
pre.editor-colors .gutter .line-number.folded,
.host .gutter .line-number.folded,
pre.editor-colors .gutter .line-number:after,
.host .gutter .line-number:after,
pre.editor-colors .fold-marker:after,
.host .fold-marker:after {
  color: #e87b00;
}
pre.editor-colors .invisible,
.host .invisible {
  color: #555;
}
pre.editor-colors .selection .region,
.host .selection .region {
  background-color: #e1e1e1;
}
pre.editor-colors.is-focused .cursor,
.host.is-focused .cursor {
  border-color: #000000;
}
pre.editor-colors.is-focused .selection .region,
.host.is-focused .selection .region {
  background-color: #afc4da;
}
pre.editor-colors.is-focused .line-number.cursor-line-no-selection,
.host.is-focused .line-number.cursor-line-no-selection,
pre.editor-colors.is-focused .line.cursor-line,
.host.is-focused .line.cursor-line {
  background-color: rgba(255, 255, 134, 0.34);
}
pre.editor-colors .source.gfm,
.host .source.gfm {
  color: #444;
}
pre.editor-colors .gfm .markup.heading,
.host .gfm .markup.heading {
  color: #111;
}
pre.editor-colors .gfm .link,
.host .gfm .link {
  color: #888;
}
pre.editor-colors .gfm .variable.list,
.host .gfm .variable.list {
  color: #888;
}
pre.editor-colors .markdown .paragraph,
.host .markdown .paragraph {
  color: #444;
}
pre.editor-colors .markdown .heading,
.host .markdown .heading {
  color: #111;
}
pre.editor-colors .markdown .link,
.host .markdown .link {
  color: #888;
}
pre.editor-colors .markdown .link .string,
.host .markdown .link .string {
  color: #888;
}
.host(.is-focused) .cursor {
  border-color: #000000;
}
.host(.is-focused) .selection .region {
  background-color: #afc4da;
}
.host(.is-focused) .line-number.cursor-line-no-selection,
.host(.is-focused) .line.cursor-line {
  background-color: rgba(255, 255, 134, 0.34);
}
.comment {
  color: #999988;
  font-style: italic;
}
.string {
  color: #D14;
}
.string .source,
.string .meta.embedded.line {
  color: #5A5A5A;
}
.string .punctuation.section.embedded {
  color: #920B2D;
}
.string .punctuation.section.embedded .source {
  color: #920B2D;
}
.constant.numeric {
  color: #D14;
}
.constant.language {
  color: #606aa1;
}
.constant.character,
.constant.other {
  color: #606aa1;
}
.constant.symbol {
  color: #990073;
}
.constant.numeric.line-number.find-in-files .match {
  color: rgba(143, 190, 0, 0.63);
}
.variable {
  color: #008080;
}
.variable.parameter {
  color: #606aa1;
}
.keyword {
  color: #222;
  font-weight: bold;
}
.keyword.unit {
  color: #445588;
}
.keyword.special-method {
  color: #0086B3;
}
.storage {
  color: #222;
}
.storage.type {
  color: #222;
}
.entity.name.class {
  text-decoration: underline;
  color: #606aa1;
}
.entity.other.inherited-class {
  text-decoration: underline;
  color: #606aa1;
}
.entity.name.function {
  color: #900;
}
.entity.name.tag {
  color: #008080;
}
.entity.other.attribute-name {
  color: #458;
  font-weight: bold;
}
.entity.name.filename.find-in-files {
  color: #E6DB74;
}
.support.constant,
.support.function,
.support.type {
  color: #458;
}
.support.class {
  color: #008080;
}
.invalid {
  color: #F8F8F0;
  background-color: #00A8C6;
}
.invalid.deprecated {
  color: #F8F8F0;
  background-color: #8FBE00;
}
.meta.structure.dictionary.json > .string.quoted.double.json,
.meta.structure.dictionary.json > .string.quoted.double.json .punctuation.string {
  color: #000080;
}
.meta.structure.dictionary.value.json > .string.quoted.double.json {
  color: #d14;
}
.meta.diff,
.meta.diff.header {
  color: #75715E;
}
.css.support.property-name {
  font-weight: bold;
  color: #333;
}
.css.constant {
  color: #099;
}
.bracket-matcher .region {
  background-color: #C9C9C9;
  opacity: .7;
  border-bottom: 0 none;
}
</style>
  </head>
  <body class='markdown-preview' data-use-github-style><h1 id="mist-user-guide">MIST User Guide</h1>
<h2 id="contents">Contents</h2>
<h4 id="-user-guide-mist-user-guide-"><a href="#mist-user-guide">User Guide</a></h4>
<ol>
<li><a href="#contents">Contents</a></li>
<li><a href="#launching-mist">Launching MIST</a></li>
<li><a href="#installation-validation-test">Installation Validation Test</a></li>
<li><a href="#mist-graphical-user-interface">MIST Graphical User Interface</a><ol>
<li><a href="#input-parameters">Input Parameters</a></li>
<li><a href="#output-parameters">Output Parameters</a></li>
<li><a href="#subgrid-parameters">Subgrid Parameters</a></li>
<li><a href="#advanced-parameters">Advanced Parameters</a><ol>
<li><a href="#java-execution">Java Execution</a></li>
<li><a href="#fftw-execution">FFTW Execution</a></li>
<li><a href="#cuda-execution">CUDA Execution</a></li>
</ol>
</li>
<li><a href="#help">Help</a></li>
</ol>
</li>
<li><a href="#mist-status-frame">MIST Status Frame</a></li>
</ol>
<hr>
<h4 id="-install-guide-mist-plugin-installation-"><a href="#mist-plugin-installation">Install Guide</a></h4>
<ol>
<li><a href="#mist-plugin-installation">MIST Plugin Installation</a><ol>
<li><a href="#update-site-installation">Update Site Installation</a></li>
<li><a href="#manual-installation">Manual Installation</a></li>
</ol>
</li>
<li><a href="#fftw-installation">FFTW Installation</a><ol>
<li><a href="#fftw-installation-on-unix-64-bit-mac-osxlinux">FFTW Installation on Unix (64-bit Mac OSX/Linux)</a></li>
<li><a href="#fftw-installation-using-macports">FFTW Installation using MacPorts</a></li>
</ol>
</li>
<li><a href="#cuda-installation">CUDA Installation</a><ol>
<li><a href="#cuda-toolkit-v65-installation-on-windowslinuxmacosx">CUDA Toolkit v6.5 installation on Windows/Linux/MacOSX</a></li>
</ol>
</li>
</ol>
<hr>
<h4 id="-faq-mist-faq-"><a href="#mist-faq">FAQ</a></h4>
<ol>
<li><a href="#contents">Contents</a></li>
<li><a href="#my-image-filename-pattern-does-not-work">My image filename pattern does not work</a><ol>
<li><a href="#sequential">Sequential</a></li>
<li><a href="#row-column">Row Column</a></li>
<li><a href="#timeslices">Timeslices</a></li>
</ol>
</li>
<li><a href="#mist-encountered-an-out-of-memory-problem">MIST encountered an Out of Memory problem</a><ol>
<li><a href="#general-memory-management">General Memory Management</a></li>
<li><a href="#java-mode">Java Mode</a></li>
<li><a href="#fftw-mode">FFTW Mode</a></li>
<li><a href="#cuda-mode">CUDA Mode</a></li>
</ol>
</li>
<li><a href="#what-image-types-can-mist-handle">What image types can MIST handle</a></li>
<li><a href="#my-stitching-results-look-incorrect">My stitching results look incorrect</a><ol>
<li><a href="#incorrect-input-parameters">Incorrect Input Parameters</a></li>
<li><a href="#unexpected-image-overlap-variability">Unexpected Image Overlap Variability</a></li>
<li><a href="#bad-stage-repeatability-estimate">Bad Stage Repeatability Estimate</a></li>
<li><a href="#noisy-input-images">Noisy Input Images</a></li>
</ol>
</li>
<li><a href="#what-if-the-output-stitched-image-is-too-big-to-be-saved">What if the output stitched image is too big to be saved</a></li>
<li><a href="#i-installed-the-cuda-toolkit-but-i-am-getting-a-cuda-exception">I installed the CUDA toolkit, but I am getting a CUDA Exception</a></li>
<li><a href="#the-fftw-version-does-not-work">The FFTW version does not work</a><ol>
<li><a href="#windows">Windows</a></li>
<li><a href="#osx">OSX</a></li>
<li><a href="#linux">Linux</a></li>
</ol>
</li>
<li><a href="#my-stitching-performance-is-not-good">My stitching performance is not good</a><ol>
<li><a href="#image-locality">Image Locality</a></li>
<li><a href="#memory-capacity">Memory Capacity</a></li>
<li><a href="#cpu-saturation">CPU Saturation</a></li>
</ol>
</li>
<li><a href="#i-have-a-gpu-in-my-machine-but-it-is-not-showing-up">I have a GPU in my machine but it is not showing up</a></li>
<li><a href="#how-to-stitch-from-metadata">How to stitch from metadata</a></li>
<li><a href="#stitching-time-slices">Stitching Time-Slices</a></li>
<li><a href="#stitching-multiple-channels">Stitching Multiple Channels</a></li>
<li><a href="#stitching-using-a-macro-script">Stitching using a Macro Script</a></li>
<li><a href="#submitting-issue-or-bug-report">Submitting issue or bug report</a></li>
</ol>
<hr>
<h3 id="launching-mist">Launching MIST</h3>
<ol>
<li>Start Fiji.</li>
<li>Click through the menus: <em>Plugins &gt;&gt; Stitching &gt;&gt; MIST</em></li>
<li>Click: <em>MIST</em></li>
</ol>
<hr>
<h3 id="installation-validation-test">Installation Validation Test</h3>
<p>In this section, we will walk through setting up running MIST on one of the 5x5 image tile datasets in order to validate that the plugin is installed correctly.</p>
<ol>
<li>Download test images: <a href="testdata/Small_Fluorescent_Test_Dataset.zip">Cy5_ImageTiles.zip ~ 54 MB</a></li>
<li>Extract Cy5_ImageTiles.zip into a directory</li>
<li><a href="#launching-mist">Launch MIST plugin from Fiji</a></li>
<li>Select <strong>Load Params</strong> and open &#39;[extractionPath]/Small_Fluorescent_Test_Dataset/stitching-params.txt&#39;</li>
<li>To manually enter parameters (avoiding <strong>Load Params</strong>) enter the following values into the Input Tab<ol>
<li><strong>Filename Pattern Type</strong>: &#39;Row-Column&#39;</li>
<li><strong>Filename Pattern</strong>: &#39;img_r{rrr}_c{ccc}.tif&#39;</li>
<li><strong>Starting Point</strong>: &#39;Upper Left&#39;</li>
<li><strong>Grid Width</strong>: &#39;5&#39;</li>
<li><strong>Grid Height</strong>: &#39;5&#39;</li>
</ol>
</li>
<li>Modify <strong>Image Directory</strong> to &#39;[extractionPath]/Small_Fluorescent_Test_Dataset/image-tiles&#39;</li>
<li>Select the Output tab and update <strong>Output Directory</strong> to define where the output files are to be saved</li>
<li>Set <strong>Blending Mode</strong>: to &#39;Overlay&#39;</li>
<li>Update <strong>Display Stitched Image</strong> and <strong>Save Full Stitched Image</strong> to selected/enabled</li>
<li>To check the parameters defining the image grid, select <strong>Preview (0% overlap)</strong> which should generate and display a zero percent overlap tiling of the input images</li>
<li>Click <strong>Begin Stitching</strong> to launch</li>
<li>Compare the newly generated stitched image to the reference stitched image shipped with the test dataset<ol>
<li>Open &#39;[extractionPath]/Small_Fluorescent_Test_Dataset/stitched-image/img-stitched-0.tif&#39; in Fiji.</li>
<li>Check that the new stitched image has the same dimensions as the reference</li>
<li>Perform a pixel-wise comparison between the stitched images</li>
<li>Fiji&gt;&gt;Process&gt;&gt;Image Calculator</li>
<li>The operation new stitched image &quot;Difference&quot; reference stitched image should produce an image containing all zeros when using the correct parameters</li>
</ol>
</li>
</ol>
<hr>
<h3 id="mist-graphical-user-interface">MIST Graphical User Interface</h3>
<p>The MIST plugin consists of five tabs. Below, we outline each tab and discuss all of the parameters. All options labeled with an * are required in order to start stitching. Each tab contains a <strong>?</strong> button that, when clicked, generates a local copy of this documentation.</p>
<hr>
<h4 id="input-parameters">Input Parameters</h4>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/InputWindow.png" alt=""></p>
<blockquote>
<p><strong>Save Params</strong> Button - Saves all parameters in MIST to a file.</p>
<p><strong>Preview (0% overlap)</strong> Button - Opens the image mosaic into Fiji assuming 0% overlap.</p>
<p><strong>Begin Stitching</strong> Button - Launches the stitching experiment.</p>
<p><strong>Load Params</strong> Button - Loads parameters from a file. Note: <em>Supports loading the statistics file that is generated after each experiment.</em></p>
<p>* <strong>Filename Pattern Type</strong> - Used to specify the type of filename pattern used in the acquired images. Possible options: <strong>Sequential</strong> and <strong>Row-Column</strong>.</p>
<p>Sequential:</p>
<pre class="editor-colors lang-text"><div class="line"><span class="text plain"><span>&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="meta paragraph text"><span>Sequential&nbsp;pattern&nbsp;images&nbsp;have&nbsp;a&nbsp;single&nbsp;number&nbsp;representing&nbsp;their&nbsp;position&nbsp;within&nbsp;the&nbsp;image&nbsp;grid.</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;Example:&nbsp;img_pos001_c01.tif&nbsp;=&nbsp;img_pos{ppp}_c01.tif</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;{ppp}&nbsp;-&nbsp;Special&nbsp;text&nbsp;that&nbsp;represents&nbsp;position&nbsp;numbering&nbsp;between&nbsp;0&nbsp;and&nbsp;999.&nbsp;Increase&nbsp;the&nbsp;number&nbsp;of&nbsp;p&#39;s&nbsp;to&nbsp;represent&nbsp;larger&nbsp;numbers.</span></span></span></div></pre><p>Row-Column:</p>
<pre class="editor-colors lang-text"><div class="line"><span class="text plain"><span>&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="meta paragraph text"><span>Row-Column&nbsp;pattern&nbsp;images&nbsp;have&nbsp;a&nbsp;pair&nbsp;of&nbsp;numbers&nbsp;representing&nbsp;their&nbsp;position&nbsp;within&nbsp;the&nbsp;image&nbsp;grid.</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;Example:&nbsp;img_r01_c01.tif&nbsp;=&nbsp;img_r{rr}_c{cc}.tif</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;{rr}&nbsp;-&nbsp;Special&nbsp;text&nbsp;that&nbsp;represents&nbsp;row&nbsp;numbering&nbsp;between&nbsp;0&nbsp;and&nbsp;99.&nbsp;Increase&nbsp;the&nbsp;number&nbsp;of&nbsp;r&#39;s&nbsp;to&nbsp;represent&nbsp;larger&nbsp;numbers.</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;{cc}&nbsp;-&nbsp;Special&nbsp;text&nbsp;that&nbsp;represents&nbsp;column&nbsp;numbering&nbsp;between&nbsp;0&nbsp;and&nbsp;99.&nbsp;Increase&nbsp;the&nbsp;number&nbsp;of&nbsp;c&#39;s&nbsp;to&nbsp;represent&nbsp;larger&nbsp;numbers.</span></span></span></div></pre><p>* <strong>Starting Point</strong> - The starting point of the microscope scan. Possible options: <strong>Upper Left</strong>, <strong>Upper Right</strong>, <strong>Lower Left</strong>, and <strong>Lower Right</strong>. This specifies the origin for the grid of images.</p>
<p>* <strong>Direction</strong> - The direction and pattern of the microscope motion during acquisition. Possible options: <strong>Vertical Combing</strong>, <strong>Vertical Continuous</strong>, <strong>Horizontal Combing</strong>, and <strong>Horizontal Continuous</strong>.</p>
<p>* <strong>Grid Width</strong> - The number of images in a row (The number of columns, the width of the image grid)</p>
<p>* <strong>Grid Height</strong> - The number of images in a column. (The number of rows, the height of the image grid)</p>
<p><strong>Timeslices</strong> - The number of timeslices to stitch. Leave this field blank to stitch all timeslices. To stitch timeslices you must add the spcial format text <strong>{ttt}</strong> to the <strong>File Pattern</strong>. This input supports a comma separated list and/or a range using a &#39;-&#39;.
         Example: &quot;1-25,35,45&quot; stitches timeslices 1 through 25, 35, and 45.</p>
<p><strong>Discover Width/Height</strong> Button - Attempts to automatically discover the width and height of a row-column filename pattern type acquisition given a valid filename pattern and image directory.</p>
<p>* <strong>Filename Pattern</strong> - Used to load images from a directory. Changes based on the <strong>Filename Pattern Type</strong>. Important: the character &quot;%&quot; cannot be used as part of a filename pattern.</p>
<ul>
<li><p>If the <strong>Filename Pattern Type</strong> = <strong>Sequential</strong>, then the <strong>Filename Pattern</strong> expects sequential style numbering. We support all filename types that ImageJ supports. For a list of supported types, please refer to <a href="http://rsb.info.nih.gov/ij/docs/guide/146-7.html">ImageJ User Guide</a></p>
<pre class="editor-colors lang-text"><div class="line"><span class="text plain"><span>&nbsp;&nbsp;</span><span class="meta paragraph text"><span>Example&nbsp;1:&nbsp;Img_pos0001_c01.tif&nbsp;=&nbsp;Img_pos{pppp}_c01.tif</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;Examples&nbsp;2:&nbsp;Img_pos001_time001.tif&nbsp;=&nbsp;Img_pos{ppp}_time{ttt}.tif</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;{ppp}&nbsp;-&nbsp;Special&nbsp;text&nbsp;that&nbsp;represents&nbsp;position&nbsp;numbering&nbsp;between&nbsp;0&nbsp;and&nbsp;999.&nbsp;Increase&nbsp;the&nbsp;number&nbsp;of&nbsp;p&#39;s&nbsp;to&nbsp;represent&nbsp;larger&nbsp;numbers.</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;{ttt}&nbsp;-&nbsp;Special&nbsp;text&nbsp;that&nbsp;represents&nbsp;timeslice&nbsp;number&nbsp;between&nbsp;0&nbsp;and&nbsp;999.&nbsp;Each&nbsp;value&nbsp;of&nbsp;{ttt}&nbsp;will&nbsp;be&nbsp;stitched&nbsp;independently.&nbsp;Increase&nbsp;the&nbsp;number&nbsp;of&nbsp;t&#39;s&nbsp;to&nbsp;represent&nbsp;larger&nbsp;numbers.&nbsp;Specifying&nbsp;time&nbsp;slices&nbsp;is&nbsp;optional.</span></span></span></div></pre></li>
<li><p>If the <strong>Filename Pattern Type</strong> = <strong>Row-Column</strong>, then the <strong>Filename Pattern</strong> expects row-column style numbering.</p>
<pre class="editor-colors lang-text"><div class="line"><span class="text plain"><span>&nbsp;&nbsp;</span><span class="meta paragraph text"><span>Example&nbsp;1:&nbsp;Img_r1_c1.tif&nbsp;=&nbsp;Img_r{r}_c{c}.tif</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;Example&nbsp;2:&nbsp;Img_row01_col01_time01.tif&nbsp;=&nbsp;Img_row{rr}_col{cc}_time{tt}.tif</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;{rr}&nbsp;-&nbsp;Special&nbsp;text&nbsp;for&nbsp;row&nbsp;numbering&nbsp;between&nbsp;0&nbsp;and&nbsp;99.&nbsp;Increase&nbsp;the&nbsp;number&nbsp;of&nbsp;r&#39;s&nbsp;to&nbsp;represent&nbsp;larger&nbsp;numbers.</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;{cc}&nbsp;-&nbsp;Special&nbsp;text&nbsp;for&nbsp;column&nbsp;numbering&nbsp;between&nbsp;0&nbsp;and&nbsp;99.&nbsp;Increase&nbsp;the&nbsp;number&nbsp;of&nbsp;c&#39;s&nbsp;to&nbsp;represent&nbsp;larger&nbsp;numbers.</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;{ttt}&nbsp;-&nbsp;Special&nbsp;text&nbsp;that&nbsp;represents&nbsp;timeslice&nbsp;number&nbsp;between&nbsp;0&nbsp;and&nbsp;999.&nbsp;Each&nbsp;value&nbsp;of&nbsp;{ttt}&nbsp;will&nbsp;be&nbsp;stitched&nbsp;independently.&nbsp;Increase&nbsp;the&nbsp;number&nbsp;of&nbsp;t&#39;s&nbsp;to&nbsp;represent&nbsp;larger&nbsp;numbers.&nbsp;Specifying&nbsp;time&nbsp;slices&nbsp;is&nbsp;optional.</span></span></span></div></pre></li>
</ul>
<p>* <strong>Image Directory</strong> - The directory where the source images are located. Select browse to open a directory browser.</p>
<p><strong>Assemble from metadata</strong> - Generates the image mosaic using metadata from a previous run. <strong>Important</strong>: You must specify the global-positions file to use in the <strong>Global Positions File</strong> field. If your <strong>Filename Pattern</strong> has a time slice iterator &quot;{tt}&quot; then the global-positions file specified must also.</p>
<p><strong>Global Positions File</strong> - The filepath to the global-positions file to use in assembling from metadata. Note: this must be the filepath of an individual global-positions file, not the directory containing a global-positions file. Note: If you <strong>Filename Pattern</strong> has a time slice iterator &quot;{tt}&quot; then the global-positions file specified must also.</p>
</blockquote>
<hr>
<h4 id="output-parameters">Output Parameters</h4>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/OutputWindow.png" alt=""></p>
<blockquote>
<p><strong>Use Image Directory as Output Directory</strong> - Sets the output directory to be the same as the input directory.</p>
<p><strong>Output Directory</strong> - Specifies the location to save images and run statistics.</p>
<p>Files that are saved:</p>
<ul>
<li><strong>{namePrefix}</strong>stitched-<strong>{#}</strong>.tiff</li>
<li><strong>{namePrefix}</strong>statistics.txt</li>
<li>global-positions-<strong>{#}</strong>.txt</li>
<li>relative-positions-<strong>{#}</strong>.txt</li>
<li>relative-positions-no-optimization-<strong>{#}</strong>.txt</li>
<li>hillclimb-startings-positions-<strong>{#}</strong>.txt<pre class="editor-colors lang-text"><div class="line"><span class="text plain"><span>&nbsp;&nbsp;</span><span class="meta paragraph text"><span>{namePrefix}&nbsp;-&nbsp;the&nbsp;prefix&nbsp;used&nbsp;in&nbsp;&quot;Filename&nbsp;Prefix&quot;</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;{#}&nbsp;-&nbsp;The&nbsp;timeslice&nbsp;number&nbsp;(0&nbsp;if&nbsp;no&nbsp;timeslices&nbsp;are&nbsp;used)</span></span></span></div></pre></li>
</ul>
<p><strong>Filename Prefix</strong> - The prefix given to output files.</p>
<p><strong>Blending mode</strong> - Selects the blending mode to be used for computing the mosaic image.
Blending Types:</p>
<ul>
<li>Overlay - Choose only one pixel from overlapping pixels based on highest accuracy</li>
<li>Linear - Smoothly alters the intensity of the overlapping area between images. Smoothness is determined by alpha. Value should be between (0, 5]</li>
<li>Average - Computes the average intensity</li>
</ul>
<p><strong>Warning:</strong>: <em>RGB images may cause out of memory issues for linear and average blending. When generating the mosaic of RBG images it is recommended to use overlay images.</em></p>
<p><strong>Display Stitched Image</strong> - Opens the blended image mosaic into Fiji.</p>
<p><strong>Save Full Stitched Image</strong> - Writes the blended image mosaic to the <strong>Output Directory</strong>.</p>
<p><strong>Update</strong> Button - Updates the estimated stitched image file size.</p>
<p><strong>Warning</strong>: <em>Large image grids can cause out of memory errors. If the number of pixels in the output stitched image exceeds 2147483647 (2<sup>31</sup>-1), then the stitched image must be exported using an alternative method. (imagePixelWidth*imagePixelHeight &lt; 2147483647)</em></p>
</blockquote>
<hr>
<h4 id="subgrid-parameters">Subgrid Parameters</h4>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/SubgridWindow.png" alt=""></p>
<blockquote>
<p><strong>Use full grid</strong> - Updates the subgrid to use the full grid of images.</p>
<p><strong>Start Col</strong> - The start column for the subgrid.</p>
<p><strong>Start Row</strong> - The start row for the subgrid.</p>
<p><strong>Extent Width</strong>- The width for the subgrid.</p>
<p><strong>Extent Height</strong> - The height for the subgrid.</p>
<p><strong>Suppress SubGrid Warning Dialog Box</strong> - suppress the warning dialog box that gets displayed when stitching a subgrid. The warning dialog is useful if you infrequently stitch subgrids to prevent inadvertently stitching a subgrid.</p>
</blockquote>
<hr>
<h4 id="advanced-parameters">Advanced Parameters</h4>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/AdvancedWindow.png" alt=""></p>
<blockquote>
<p><strong>Stage Repeatability</strong> - Sets the stage repeatability variable when computing the global optimization. This value is used to represent the repeatability of the microscope stage movement. It is used for determining the search space of the hill climbing algorithm. This value is specified in pixels.</p>
<p><strong>Horizontal overlap</strong> - Sets the horizontal overlap variable when computing the global optimization. This value is used to filter translations as good or bad. Good translations are used to identify the optimal starting position for the hill climbing algorithm. Setting this value can improve the accuracy of the image mosaic. This value is specified in percent. The value must be between 0 and 100.</p>
<p><strong>Vertical overlap</strong> - Sets the vertical overlap variable when computing the global optimization. This value is used to filter translations as good or bad. Good translations are used to identify the optimal starting position for the hill climbing algorithm. Setting this value can improve the accuracy of the image mosaic. This value is specified in percent. The value must be between 0 and 100.</p>
<p><strong>Overlap uncertainty</strong> - Sets the overlap uncertainty variable when computing the global optimization. This value is used to specify the range when filtering translations as good or bad. It is used in conjunction with the horizontal and vertical overlap variables. This value is specified in percent. The value must be between 0 and 100. This value should generally not exceed 10. (Default: 3)</p>
<p><strong>Use BioFormats Image Reader?</strong> - Specifies whether to use the BioFormats image reader as opposed to the ImageJ image reader. The ImageJ reader supports most common image file types and is faster than BioFormats. If the ImageJ reader cannot read an image being stitched, try using BioFormats as it supports more image types.</p>
<p><strong>Use Double Precision Math?</strong> - Specifies whether the FFTs and other stitching computation is done using 32bit floats of 64bit doubles. The default is 32bit, but if you are not getting a satisfactory stitching try using double precision.</p>
<p><strong>Translation Refinement Method</strong> - Specifies the type of translation refinement that is performed. Once the translations between images have been computed, the stage model is built to constrain the translations to reasonable values. Within the search space defined by the stage model an optimization of the pairwise translations takes place. The method of translation optimization/refinement is selected here. The default is a single hill climbing starting at the computed/estimated translation. This is the fastest option. If this proves ineffective for your dataset, multipoint hill climbing is available where, in addition to performing a hill climbing starting at the computed/estimated translation, <em>n</em> starting points are randomly selected within the search bounds and allowed to converge to local maxima. The number of starting points is user selected (default of 16). This is more robust than the single hill climb, but more computationally intensive. The final option, Exhaustive, checks every possible translation within the stage model bounds. This is extremely slow.</p>
<p><strong>Number of FFT Peaks</strong> - Specifies the number of peaks to check when computing the phase correlation image alignment method. We have determined that modifying this value can yield more accurate pre-optimization displacements. This value should not exceed 10. (Default: 2)</p>
<p><strong>Log Level</strong> - Sets the log level for the user interface and the stitching execution.
Possible Options:</p>
<ul>
<li>None - No logging</li>
<li>Mandatory - Logs important information</li>
<li>Helpful - Logs helpful information</li>
<li>Info - Logs informative information</li>
<li>Verbose - Logs all information</li>
</ul>
<p><em>Note: The lower logging stack includes the logging levels above. Example: Helpful, includes Mandatory.</em></p>
<p><strong>Debug Level</strong> - Sets the debug level for the user interface and the stitching execution.
Possible Options:</p>
<ul>
<li>None - No debug logging</li>
<li>Mandatory - Logs important debug information</li>
<li>Helpful - Logs helpful debug information</li>
<li>Info - Logs informative debug information</li>
<li>Verbose - Logs all debug information</li>
</ul>
<p><em>Note: The lower logging stack includes the logging levels above. Example: Helpful, includes Mandatory.</em></p>
<p><strong>Stitching Program</strong> - Selects which type of program to execute.</p>
<ul>
<li>Auto - Determine which program to use. First checks if FFTW is available, if it is not then it falls back to Java.</li>
<li>Java - Uses the pure java implementation. This version uses single precision values, but is not as accurate as FFTW and CUDA.</li>
<li>FFTW - Uses FFTW libraries.</li>
<li>CUDA - Uses NVIDIA CUDA GPUs.</li>
</ul>
<hr>
</blockquote>
<h5 id="java-execution">Java Execution</h5>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/JavaWindow.png" alt=""></p>
<blockquote>
<p><strong>CPU worker threads</strong> - Number of parallel workers to spawn (should not exceed number of CPU cores)</p>
</blockquote>
<hr>
<h5 id="fftw-execution">FFTW Execution</h5>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/FftwWindow.png" alt=""></p>
<blockquote>
<p><strong>CPU worker threads</strong> - Number of parallel workers to spawn (should not exceed number of CPU cores)</p>
<p><strong>FFTW Plan Type</strong> - The type of FFTW plan to generate</p>
<ul>
<li>Measure - Default, short creation time, usually ideal runtimes</li>
<li>Patient - Long planning time, more robust runtimes</li>
<li>Exhaustive - Very long planning time, most robust runtimes</li>
</ul>
<p><em>Note: FFTW plans can be saved and reused to eliminate planning time.</em></p>
<p><strong>Save Plan?</strong> - Saves the FFTW plan that is generated to file.</p>
<p><strong>Load Plan?</strong> - Loads the FFTW plan from file.</p>
<p><strong>FFTW Library File</strong> - Specifies the FFTW library file to load.
Example Files:</p>
<ul>
<li>Windows: libfftw3.dll (this library is packaged with MIST in the &quot;Fiji.app/lib/fftw&quot; directory)</li>
<li>Linux: libfftw3.so (default installation location &quot;/usr/local/lib&quot;)</li>
<li>Mac OSX: libfftw3.dylib (default installation location &quot;/usr/local/lib&quot;)</li>
</ul>
<p><strong>Plan Location (or file)</strong> - The location to load FFTW plans. If a file is specified, the file will be used when loading the plan. This path is also used for saving plans.</p>
<p><em>Note: <a href="https://github.com/USNISTGOV/MIST/wiki/Install-Guide#fftw-installation">FFTW installation instructions</a></em></p>
</blockquote>
<hr>
<h5 id="cuda-execution">CUDA Execution</h5>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/CudaWindow.png" alt=""></p>
<blockquote>
<p><strong>CPU worker threads</strong> - Number of parallel workers to spawn (should not exceed number of CPU cores)</p>
<p><strong>Execute Device Query</strong> - Queries for all GPUs installed on the system and prints the information to the log.</p>
<p><strong>Refresh Device Table</strong> - Forces the table to re-query all GPUs and repopulate the table.</p>
<p><strong>GPU Table</strong> - Displays all available GPUs found on the machine. To use one (or more) GPUs, click the check box in the <strong>Selected?</strong> column.
<em>Note: GPUs have limited memories, it is recommended to use GPUs with at least 1 GB of graphics memory depending on the size of the image grid.</em></p>
<p><em>Note: <a href="https://github.com/USNISTGOV/MIST/wiki/Install-Guide#cuda-installation">CUDA Installation instructions</a></em></p>
</blockquote>
<hr>
<h4 id="help">Help</h4>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/HelpWindow.png" alt=""></p>
<blockquote>
<p><strong>Open Local Help Documentation</strong> - Opens this document without an Internet connection.</p>
</blockquote>
<hr>
<h3 id="mist-status-frame">MIST Status Frame</h3>
<p><img src="https://github.com/usnistgov/MIST.wiki/images/MISTStatus.png" alt=""></p>
<blockquote>
<p><strong>Progress</strong> - If timeslices are used, shows the current timeslice, total timeslices, and number of groups (if entered as a comma separated list in the input parameters).</p>
<p><strong>Progress bar</strong> - Shows the % progress made for the current experiment.</p>
<p><strong>Log Level</strong> - Sets the log level for the user interface and the stitching execution.
Possible Options:</p>
<ul>
<li>None - No logging</li>
<li>Mandatory - Logs important information</li>
<li>Helpful - Logs helpful information</li>
<li>Info - Logs informative information</li>
<li>Verbose - Logs all information</li>
</ul>
<p><em>Note: The lower logging stack includes the logging levels above. Example: Helpful, includes Mandatory.</em></p>
<p><strong>Debug Level</strong> - Sets the debug level for the user interface and the stitching execution.
Possible Options:</p>
<ul>
<li>None - No debug logging</li>
<li>Mandatory - Logs important debug information</li>
<li>Helpful - Logs helpful debug information</li>
<li>Info - Logs informative debug information</li>
<li>Verbose - Logs all debug information</li>
</ul>
<p><em>Note: The lower logging stack includes the logging levels above. Example: Helpful, includes Mandatory.</em></p>
<p><strong>Cancel Execution</strong> - Safely stops execution and releases used resources.</p>
</blockquote>
<hr>
<p>* - required in order to start stitching</p>
<hr>
<hr>
<h1 id="mist-plugin-installation">MIST Plugin Installation</h1>
<p>Installing the plugin into <a href="http://fiji.sc/Fiji">Fiji</a> is simplified using Fiji&#39;s update site manager. If the machine is not configured for the network then please refer to the <a href="#manual-installation">manual installation</a>.</p>
<h3 id="update-site-installation">Update Site Installation</h3>
<ol>
<li>Open Fiji</li>
<li>Help &gt;&gt; Update Fiji</li>
<li>Manage update sites</li>
<li>Activate <strong>MIST</strong> by selecting check box</li>
<li>Close and Apply Changes</li>
<li>Plugin is installed in Plugin &gt;&gt; Stitching &gt;&gt; MIST</li>
</ol>
<p>Or</p>
<ol>
<li>Open Fiji</li>
<li>Help &gt;&gt; Update Fiji</li>
<li>Manage update sites</li>
<li>Click &quot;Add&quot;</li>
<li>Enter Name: &quot;MIST&quot; and URL: <a href="http://sites.imagej.net/NIST-ISG-MIST/">http://sites.imagej.net/NIST-ISG-MIST/</a></li>
<li>Close and Apply Changes</li>
<li>Plugin is installed in Plugin &gt;&gt; Stitching &gt;&gt; MIST</li>
</ol>
<h3 id="manual-installation">Manual Installation</h3>
<ol>
<li>Download the latest version of the MIST plugin from <a href="https://isg.nist.gov/deepzoomweb/resources/csmet/pages/image_stitching/downloads/MIST-plugin.zip">MIST Plugin Download</a></li>
<li>Extract the contents of the zip file into your Fiji.app folder</li>
<li>Restart Fiji</li>
<li>Plugin is installed in Plugins &gt;&gt; Stitching &gt;&gt; MIST</li>
</ol>
<h1 id="fftw-installation">FFTW Installation</h1>
<p>FFTW (Fastest Fourer Transform in the West, <a href="http://fftw.org">http://fftw.org</a> ) is a C implementation out of MIT that computes the discrete Fourier transform. The plugin loads the library at run-time and uses the high performance FFTW functions in Java.</p>
<p><strong>Requirements:</strong></p>
<ol>
<li>Fiji (64-bit version)</li>
</ol>
<p>Note: <em>64-bit Windows systems should be able to run the FFTW version without additional setup.</em></p>
<h2 id="fftw-installation-on-unix-64-bit-mac-osx-linux-">FFTW Installation on Unix (64-bit Mac OSX/Linux)</h2>
<ol>
<li>Download fftw-3.3.4.tar.gz from <a href="http://www.fftw.org/download.html">http://www.fftw.org/download.html</a></li>
<li>Extract source code to directory (terminal command: &quot;tar -xzvf fftw-3.3.4.tar.gz&quot;)</li>
<li>From a terminal locate source code and run the following commands to compile the 32bit and 64bit versions:</li>
</ol>
<blockquote>
<pre class="editor-colors lang-text"><div class="line"><span class="text plain"><span>&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="meta paragraph text"><span>./configure&nbsp;--enable-shared</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;make</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;sudo&nbsp;make&nbsp;install</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;./configure&nbsp;--enable-float&nbsp;--enable-shared</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;make</span></span></span></div><div class="line"><span class="text plain"><span class="meta paragraph text"><span>&nbsp;&nbsp;&nbsp;&nbsp;sudo&nbsp;make&nbsp;install</span></span></span></div></pre></blockquote>
<p> (If configure fails, additional compilers and/or libraries may be needed)</p>
<ol>
<li>Launch the Fiji MIST plugin</li>
<li>Specify the FFTW library file in the <em>Advanced FFTW Options</em> <a href="https://github.com/USNISTGOV/MIST/wiki/User-Guide#fftw-execution">FFTW options user guide</a>  (default FFTW installation location is in /usr/local/lib)<ol>
<li>Linux library name example: <em>libfftw3.so</em> (or similar)</li>
<li>MacOSX library name example: <em>libfftw3.dylib</em> (or similar)</li>
</ol>
</li>
<li>You should now be able to launch MIST using FFTW</li>
</ol>
<h2 id="fftw-installation-using-macports">FFTW Installation using MacPorts</h2>
<ol>
<li>From the command-line: <code>sudo port install fftw-3</code></li>
<li>Launch the Fiji MIST plugin</li>
<li>Specify the FFTW library file in the <em>Advanced FFTW Options</em> <a href="https://github.com/USNISTGOV/MIST/wiki/User-Guide#fftw-execution">FFTW options user guide</a>  (default FFTW installation location is in /usr/local/lib)<ol>
<li>Linux library name example: <em>libfftw3.so</em> (or similar)</li>
<li>MacOSX library name example: <em>libfftw3.dylib</em> (or similar)</li>
</ol>
</li>
<li>You should now be able to launch MIST using FFTW</li>
</ol>
<h1 id="cuda-installation">CUDA Installation</h1>
<p>CUDA is the Compute Unified Device Architecture and is a language developed by NVIDIA. It is used to execute code on NVIDIA GPUs to obtain high performance.</p>
<p><strong>Requirements:</strong></p>
<ol>
<li>NVIDIA GPU installed on your system (compute capability 3.0 or better, equivalent to Kepler architecture or newer)</li>
<li>CUDA toolkit version 6.5</li>
<li>Fiji 64-bit</li>
</ol>
<p>Once the CUDA toolkit is installed a computer restart might be required before stitching can take advantage of your GPU.</p>
<h3 id="cuda-toolkit-v6-5-installation-on-windows-linux-macosx">CUDA Toolkit v6.5 installation on Windows/Linux/MacOSX</h3>
<ol>
<li>Download CUDA toolkit v6.5 for the appropriate operating system version <a href="https://developer.nvidia.com/cuda-toolkit-65">CUDA Toolkit 6.5</a></li>
<li>Install the CUDA Tookit<ol>
<li>For Windows: Launch the executable and complete the installation</li>
<li>For MacOSX: <a href="http://docs.nvidia.com/cuda/cuda-getting-started-guide-for-mac-os-x/index.html#axzz34MbYZuma">Toolkit MacOSX installation guide</a></li>
<li>For Linux: <a href="http://docs.nvidia.com/cuda/cuda-getting-started-guide-for-linux/index.html#axzz34MbYZuma">Toolkit Linux installation guide</a></li>
</ol>
</li>
<li>Restart your computer</li>
<li>Open Fiji and run MIST plugin</li>
<li>CUDA option should be available in the MIST plugin.</li>
</ol>
<hr>
<hr>
<h1 id="mist-faq">MIST FAQ</h1>
<h2 id="contents">Contents</h2>
<ol>
<li><a href="#my-image-filename-pattern-does-not-work">My image filename pattern does not work</a></li>
<li><a href="#mist-encountered-an-out-of-memory-problem">MIST encountered an Out of Memory problem</a></li>
<li><a href="#what-image-types-can-mist-handle">What image types can MIST handle</a></li>
<li><a href="#my-stitching-results-look-incorrect">My stitching results look incorrect</a></li>
<li><a href="#what-if-the-output-stitched-image-is-too-big-to-be-saved">What if the output stitched image is too big to be saved</a></li>
<li><a href="#i-installed-the-cuda-toolkit-but-i-am-getting-a-cuda-exception">I installed the CUDA toolkit, but I am getting a CUDA Exception</a></li>
<li><a href="#the-fftw-version-does-not-work">The FFTW version does not work</a></li>
<li><a href="#my-stitching-performance-is-not-good">My stitching performance is not good</a></li>
<li><a href="#i-have-a-gpu-in-my-machine-but-it-is-not-showing-up">I have a GPU in my machine but it is not showing up</a></li>
<li><a href="#how-to-stitch-from-metadata">How to stitch from metadata</a></li>
<li><a href="#stitching-time-slices">Stitching Time-Slices</a></li>
<li><a href="#stitching-multiple-channels">Stitching Multiple Channels</a></li>
<li><a href="#stitching-using-a-macro-script">Stitching using a Macro Script</a></li>
<li><a href="#submitting-issue-or-bug-report">Submitting issue or bug report</a></li>
</ol>
<hr>
<h2 id="my-image-filename-pattern-does-not-work">My image filename pattern does not work</h2>
<p>The <strong>Filename Pattern</strong> is used to match specific image files within the <strong>Image Directory</strong>.</p>
<p>There are two types of <strong>Filename Pattern</strong>, <a href="#sequential">Sequential</a> and <a href="#row-column">Row-Column</a>, both of which can handle <a href="#timeslices">Timeslices</a>.</p>
<p>MIST adopts the ImageJ/Fiji notation of using curly brackets &quot;{&quot; and &quot;}&quot; to denote a block of characters that are replaced with numbers. The block &quot;{ppp}&quot;, where the character &quot;p&quot; is a placeholder for a number digit, represents numbers from 000 to 999. Each letter between two curly brackets is replaced with a digit between 0 and 9.</p>
<h4 id="sequential">Sequential</h4>
<p>Sequential <strong>Filename Pattern Type</strong>s have only one set of curly brackets &quot;{}&quot; that denotes the image&#39;s position in the image grid. The special character &quot;p&quot; must be used between the curly brackets. Therefore, a valid sequential filename pattern must have one set of curly brackets &quot;{p}&quot; with at least one &quot;p&quot; character between the curly brackets.</p>
<p>Examples:</p>
<ul>
<li>Img_pos001.tif = Img_pos{ppp}.tif</li>
<li>Img0001.png = Img{pppp}.png</li>
<li>ImageName01.tif = ImageName{pp}.tif</li>
<li>If a dataset has a sequence of 789 files<ul>
<li>common name &quot;Dataset01_&quot;</li>
<li>with a 6 digit numbering (ex. Dataset01_000001.tif)</li>
<li>Then a valid filename pattern is: &quot;Dataset01_000{ppp}.tif&quot; or &quot;Dataset01_{pppppp}.tif&quot;</li>
</ul>
</li>
</ul>
<h4 id="row-column">Row Column</h4>
<p>Row-column <strong>Filename Pattern Type</strong>s have two sets of curly brackets &quot;{r}&quot; &quot;{c}&quot;. One block denotes the image&#39;s row index within the image grid and uses the special character &quot;r&quot;. The other block denotes the image&#39;s column index within the image grid and uses the special character &quot;c&quot;. For a valid row-column <strong>Filename Pattern</strong> there must be one &quot;{r}&quot; block with at least one &quot;r&quot; between the curly brackets and one &quot;{c}&quot; block with at least one &quot;c&quot; between the curly brackets.</p>
<p>Examples:</p>
<ul>
<li>Img_row01_col01.tif = Img_row{rr}_col{cc}.tif</li>
<li>Img_r0001_c0001.png = Img_r{rrrr}_c{cccc}.png</li>
<li>ImageName_001_001.tif = ImageName_{rrr}_{ccc}.tif</li>
</ul>
<p>The usage of &quot;{p}&quot; or &quot;{r}&quot; and &quot;{c}&quot; must match the <strong>Filename Pattern Type</strong> selected. If the <strong>Filename Pattern</strong> contains &quot;{p}&quot; the sequential <strong>Filename Pattern Type</strong> must be selected. If the <strong>Filename Pattern</strong> contains &quot;{r}&quot; and &quot;{c}&quot; then row-column <strong>Filename Pattern Type</strong> must be selected.</p>
<h4 id="timeslices">Timeslices</h4>
<p>MIST can also handle stitching a series of independent 2D image grids. For example a time-lapse series of image grids. The time-slice stitching is controlled by an additional set of curly brackets in the <strong>Filename Pattern</strong> with the &quot;{ttt}&quot; special text. Setting the <strong>Timeslices</strong> field in the input tab of the MIST GUI controls which of the available time-slices will be stitched. The special text &quot;{ttt}&quot; must be used regardless of whether the independent 2D image grid are time slices of z stack slices.</p>
<p>Examples:</p>
<ul>
<li>Img_pos001_time01.tif = Img_pos{ppp}_time{tt}.tif</li>
<li>Img_r0001_c0001_t001.png = Img_r{rrrr}_c{cccc}_t{ttt}.png</li>
<li>ImageName_001_001_01.tif = ImageName_{rrr}_{ccc}_{tt}.tif</li>
<li>Dataset01_000001.tif = Dataset{tt}_000{ppp}.tif</li>
</ul>
<hr>
<h2 id="mist-encountered-an-out-of-memory-problem">MIST encountered an Out of Memory problem</h2>
<p>There are four different execution modes MIST can run:</p>
<ul>
<li><a href="#java-mode">Auto</a></li>
<li><a href="#java-mode">Java</a></li>
<li><a href="#fftw-mode">FFTW</a></li>
<li><a href="#cuda-mode">CUDA</a></li>
</ul>
<p>The mode selection exists in the Advance options tab in the GUI. Auto mode uses the FFTW mode if it can find the required native libraries and the Java mode if not.</p>
<p>The FFTW and CUDA modes are more memory intensive than the Java mode.</p>
<p><strong>If you are having memory problems first check to see whether you are using 32bit or 64bit computation by looking under the advanced tab and de-selecting the &quot;Use Double Precision?&quot; checkbox.</strong></p>
<h4 id="general-memory-management">General Memory Management</h4>
<p>MIST will attempt to avoid out of memory problems by detecting the available memory and adjusting the execution accordingly. MIST will first attempt to store all the image tiles in the image grid in memory to prevent spending time re-reading. If there is not enough memory to do this, it will enable the releasing of image tiles which will result in holding just the memory pool size images in memory and re-reading image tiles as required. If there is still not enough memory, MIST will lower the number of compute threads being used to reduce the size of the required memory pool. If all these strategies fail, MIST will run the stitching using a sequential Java version which requires enough memory to hold two images and two FFT data arrays.</p>
<h4 id="java-mode">Java Mode</h4>
<p>The memory required by Java mode can be computed using the following formula, given the following four inputs.</p>
<ul>
<li><strong>w</strong> = Image Grid Width</li>
<li><strong>h</strong> = Image Grid Height</li>
<li><strong>n</strong> = Number Threads Used</li>
<li><strong>s</strong> = Image Tile Size in MB</li>
</ul>
<p>Memory Required (MB) = 6<strong>s</strong>(min(<strong>w</strong>,<strong>h</strong>) + <strong>n</strong> + 2) + 4<strong>s</strong></p>
<p>If the Java mode does not have enough memory, try increasing the amount of memory Java is allowed to use.</p>
<p>If MIST is being run through ImageJ/Fiji there is a menu option controlling the amount memory it is allowed to use. Select the menu option &quot;Edit&quot; &gt;&gt; &quot;Options&quot; &gt;&gt; &quot;Memory &amp; Threads ...&quot; which opens a dialog box containing an option &quot;Maximum memory:&quot; in MB. Increase this value and select &quot;Ok&quot;. A reasonable value is about 75% of the available system memory. Restart Fiji to apply the new memory limit and re-launch MIST to see if the memory problem persists.</p>
<p>The Fiji FAQ has a <a href="http://fiji.sc/Frequently_Asked_Questions#How_do_I_avoid_running_out_of_memory_.28OutOfMemoryError.29.3F">question</a> related to managing memory in Fiji.</p>
<p>For more advanced Fiji memory management information see the <a href="http://fiji.sc/Java_Options">Java Options</a> page maintained by the Fiji developers.</p>
<h4 id="fftw-mode">FFTW Mode</h4>
<p>The memory required by FFTW mode can be computed using the following formula, given the following four inputs.</p>
<ul>
<li><strong>w</strong> = Image Grid Width</li>
<li><strong>h</strong> = Image Grid Height</li>
<li><strong>n</strong> = Number Threads Used</li>
<li><strong>s</strong> = Image Tile Size in MB</li>
</ul>
<p>Memory Required (MB) = 10<strong>s</strong>(min(<strong>w</strong>,<strong>h</strong>) + <strong>n</strong> + 2) + 32<strong>sn</strong></p>
<p>The FFTW mode has a memory pool that holds two types of image data, the 16bit image pixel data, and the double complex FFT data (or single complex if not using 64bit computation). The size of the memory pool is determined by the size of the image grid being stitched. Memory pool size = min(gridHeight, gridWidth) + 2 + numWorkThreads. MIST iterates over the image grid in a pattern that allows the reuse of the FFT data to prevent requiring the re-computation of any FFT. There is a potential additional numWorkThreads copies of the image pixel data if the input images are not 16bit and a conversion is required from the original format to 16bit.</p>
<p>Unlike the Java mode, FFTW allocates native system memory in addition to memory within the JVM. When determining the available memory, MIST relies on the available JVM memory as an estimation of the available system memory.</p>
<h4 id="cuda-mode">CUDA Mode</h4>
<p>The memory required by CUDA mode can be computed using the following formula, given the following five inputs.</p>
<ul>
<li><strong>w</strong> = Image Grid Width</li>
<li><strong>h</strong> = Image Grid Height</li>
<li><strong>n</strong> = Number Threads Used</li>
<li><strong>s</strong> = Image Tile Size in MB</li>
<li><strong>g</strong> = Number of GPUs Used</li>
</ul>
<p>CPU Memory Required (MB) = 2<strong>s</strong>(min(<strong>w</strong>,<strong>h</strong>) + <strong>n</strong> + 2) + 24<strong>sg</strong></p>
<p>GPU Memory Required (MB) = 8<strong>s</strong>(min(<strong>w</strong>,<strong>h</strong>) + <strong>n</strong> + 2) + 24<strong>s</strong> + 48<strong>s</strong></p>
<p>The CUDA mode has two types of memory, pinned memory that exists on both the GPU and the CPU and GPU resident memory. In addition to the pinned memory, the CUDA version needs enough CPU side memory to hold the pixel data for each image tile in the memory pool. For pinned memory, there are two double (or singel) precision arrays the size of the images, and two integer arrays the size of the images. This memory is per GPU, not per memory pool element. The GPU resident memory required consists of four double (or single) precision arrays the same size of the images and one double (or single) complex array the size of the image per memory pool element. The size of the memory pool is defined by the size of the image grid, min(gridHeight, gridWidth) + 2. On the CPU side, one image tile (at 16bit precision) needs to be stored per memory pool element.</p>
<p>Unlike the Java mode, CUDA allocates native memory on the GPU in addition to memory within the JVM.</p>
<hr>
<h2 id="what-image-types-can-mist-handle">What image types can MIST handle</h2>
<p>Any image type that Fiji/ImageJ can read. MIST uses the ImageJ image reader contained within Fiji/ImageJ. The relevant ImageJ image types and formats documentation can be found online in the ImageJ documentation. <a href="http://imagej.nih.gov/ij/docs/guide/146-7.html">ImageJ Documentation on Image Types</a>.</p>
<hr>
<h2 id="my-stitching-results-look-incorrect">My stitching results look incorrect</h2>
<p>The following are possible reasons for incorrect looking stitching:</p>
<ul>
<li><a href="#incorrect-input-parameters">Incorrect Input Parameters</a></li>
<li><a href="#unexpected-image-overlap-variability">Unexpected Image Overlap Variability</a></li>
<li><a href="#bad-stage-repeatability-estimate">Bad Stage Repeatability Estimate</a></li>
<li><a href="#noisy-input-images">Noisy Input Images</a></li>
</ul>
<h4 id="incorrect-input-parameters">Incorrect Input Parameters</h4>
<p>The best way to verify the input parameters is by previewing the image grid using zero percent overlap between images. This allows you to visually check that neighboring regions look like they should overlap, and that the arrangement of images is reasonable.</p>
<p>To preview a zero percent overlap mosaic go to the Output tab in the GUI and select <strong>Preview Mosaic With No Overlap</strong>. Visually ensure that the image grid looks properly organized. Check for corresponding image features between regions that should overlap. Common errors include an incorrect <strong>Starting Point</strong>, <strong>Direction</strong>, <strong>Grid Width</strong>, or <strong>Grid Height</strong>.</p>
<p>If the zero percent overlap is taking too long to generate you can define a sub-grid using the Subgrid tab and the preview will only be generated for the subgrid.</p>
<h4 id="unexpected-image-overlap-variability">Unexpected Image Overlap Variability</h4>
<p>The image tiles must be arranged in a rectangular grid and overlap with each other. The advanced parameter percent <strong>Overlap Uncertainty</strong> (default: 3%) reflects the uncertainty in the overlap between image tiles.</p>
<p>Set the <strong>Overlap Uncertainty</strong> to reflect the variability in the overlaps between images in your dataset.</p>
<h4 id="bad-stage-repeatability-estimate">Bad Stage Repeatability Estimate</h4>
<p>MIST estimates the <strong>Stage Repeatability</strong> of the mechanical XY-Stage used to acquire the image grid.</p>
<p>The estimated repeatability is printed in the Log windows as well as in the statistics file saved in the <strong>Metadata Directory</strong>.</p>
<p>If MIST estimates an unreasonably large <strong>Stage Repeatability</strong> it is advisable to limit it to a value you know is reasonable for your stage. Conversely, if MIST estimates an unreasonably small <strong>Stage Repeatability</strong> it is advisable to increase it, allowing MIST to search a larger space trying to find the optimal translations.</p>
<p><strong>Stage Repeatability</strong> is measured in pixels.</p>
<h4 id="noisy-input-images">Noisy Input Images</h4>
<p>If the images being stitched contain a high level of noise, MIST can have trouble stitching.</p>
<p>Three potential solutions:</p>
<ol>
<li><p>Enable double precision computation within the Advanced tab. This is unlikely to solve the problem, but it will not decrease the stitching accuracy. Normally double precision computation is left off because it requires more memory without providing much (if any) accuracy increase.</p>
</li>
<li><p>Set the advanced parameter <strong>Number of FFT Peaks</strong> (default: 2) which determines how many potential translations are tested looking for an optimal one. In noisy datasets increasing this value can improve the stitching at the cost of compute time.</p>
</li>
<li><p>Pre-filter the images to remove the noise before stitching. Since there are many varieties of de-noising filters, the selection and application of a reasonable one is up to the user.</p>
</li>
</ol>
<p>If pre-filtering is used it is possible to generate a stitched image from the original images using the global positions computed from the filtered images. This is done by first stitching the filtered images (to generate the global positions metadata file) and then assembling together the stitched image from the original images and the global positions from the filtered images. See the question on <a href="#how-to-stitch-from-metadata">how to stitch from metadata</a> for details on how to perform stitching from metadata.</p>
<p>The developers are interested in problematic data sets. Issues with stitching can be submitted to nist-mist@nist.gov or <a href="https://github.com/USNISTGOV/MIST/issues">MIST Github Issues Page</a>.</p>
<hr>
<h2 id="what-if-the-output-stitched-image-is-too-big-to-be-saved">What if the output stitched image is too big to be saved</h2>
<p>MIST is written in Java which has a maximum size for any array. The ImageJ image writer that MIST relies on uses a Java array to store the pixel data imposing a limit on the size of images that can be saved.</p>
<p><strong>If the number of pixels in the output stitched image exceeds 2147483647 (2<sup>31</sup>-1) then the stitched image cannot be saved.</strong></p>
<p>In other words, the image height in pixels multiplied by the image width in pixels must be less than 2147483647.</p>
<p>If the resulting stitched image cannot be saved using MIST there are two ways to get around this. The first is to stitch a sub-gid using the sub-grid options tab. This will stitch a smaller region and if that region is smaller than the maximum size then that image can be saved. The other option is to stitch the full grid without saving or displaying the resulting stitched image. This will allow MIST to stitch the images and generate the global positions metadata file. This file contains the global positions of every image in the grid. It can then be parsed and assembled using another software package.</p>
<hr>
<h2 id="i-installed-the-cuda-toolkit-but-i-am-getting-a-cuda-exception">I installed the CUDA toolkit, but I am getting a CUDA Exception</h2>
<p>Installing the CUDA toolkit might require a restart after the installation completes. If you attempt to run the MIST CUDA stitching before performing the restart you might get a CUDA Initialization error. If this happens restart your machine to allow the CUDA device to be initialized when MIST starts.</p>
<p>Alternatively, ensure that you have the correct version of the CUDA toolkit installed. See the <a href="https://github.com/USNISTGOV/MIST/wiki/Install-Guide">Install Guide</a> for details.</p>
<hr>
<h2 id="the-fftw-version-does-not-work">The FFTW version does not work</h2>
<p>If the FFTW <strong>Stitching Program</strong> type does not work the most likely reason is MIST cannot find the required library file.</p>
<p>FFTW uses compiled native libraries to perform fast Fourier Transforms. Without these native libraries the FFTW version cannot run.</p>
<p>Details are available by operating system:</p>
<ul>
<li><a href="#windows">Windows</a></li>
<li><a href="#osx">OSX</a></li>
<li><a href="#linux">Linux</a></li>
</ul>
<h4 id="windows">Windows</h4>
<p>For Windows the correct FFTW library file should have been included with the plugin installation. To confirm this navigate to the folder where Fiji is installed. Then confirm the file &quot;libfftw3.dll&quot; exists in the path &quot;lib&quot; &gt;&gt; &quot;fftw&quot; in the directory Fiji is installed. The file might not be named exactly &quot;libfftw3.dll&quot;, however it will always end in &quot;.dll&quot;. If that file exists then confirm that MIST is pointing at that location in the advanced parameters tab. Open MIST, select the Advanced tab, select the FFTW <strong>Stitching Program</strong> type. Verify that <strong>FFTW Library File</strong> contains the path to the &quot;libfftw3.dll&quot; file you confirmed exists. Ensure the path does not just point to the correct folder, make sure that it points right at the library file. For example, &quot;C:\Fiji.app\lib\fftw\libfftw3.dll&quot;.</p>
<h4 id="osx">OSX</h4>
<p>For OSX (Mac) you must install FFTW before you are able to use the FFTW <strong>Stitching Program</strong> type. See the FFTW <a href="https://github.com/USNISTGOV/MIST/wiki/Install-Guide">installation guide</a> for instructions on how to install FFTW.</p>
<p>Once FFTW in installed ensure that the <strong>FFTW Library File</strong> parameter under the MIST Advanced parameters tab points to the location where FFTW was installed. The library file should end with &quot;.dylib&quot;. The default location for the FFTW library is in &quot;/usr/local/lib&quot;.</p>
<h4 id="linux">Linux</h4>
<p>For Linux you must install FFTW before you are able to use the FFTW Stitching Program type. See the FFTW <a href="https://github.com/USNISTGOV/MIST/wiki/Install-Guide">installation guide</a> for instructions on how to install FFTW.</p>
<p>Once FFTW in installed ensure that the &quot;FFTW Library File&quot; parameter under the MIST advanced parameters tab points to the location where FFTW was installed. The library file should end with &quot;.so&quot;. The default location for the FFTW library is in &quot;/usr/local/lib&quot;.</p>
<hr>
<h2 id="my-stitching-performance-is-not-good">My stitching performance is not good</h2>
<p>There are many factors that can impact the performance of the MIST stitching:</p>
<ul>
<li><a href="#image-locality">Image Locality</a></li>
<li><a href="#memory-capacity">Memory Capacity</a></li>
<li><a href="#cpu-saturation">CPU Saturation</a></li>
</ul>
<h4 id="image-locality">Image Locality</h4>
<p>The largest factor in the stitching performance is where the images are located.</p>
<p>MIST is designed with the expectation that the image to be stitched are stored on a local internal hard drive on the computer performing the stitching.</p>
<p><strong>When possible copy the images to be stitched to a local hard drive before performing stitching.</strong></p>
<p>Other image location options are included here ranked from slowest to fastest:</p>
<ol>
<li>Network hard drive connected using LAN (Ethernet)</li>
<li>Any external drive connected using USB</li>
<li>Local hard drive</li>
<li>Local SSD</li>
</ol>
<p>If the images are not local, read time will dominate the stitching time.</p>
<h4 id="memory-capacity">Memory Capacity</h4>
<p>If the images are stored on a local disk, the next performance bottleneck is a lack of system memory.</p>
<p>If the computer performing the stitching does not have enough memory to hold all image tiles in memory, tiles will be release and re-read as required slowing down the computation.</p>
<p>When possible MIST will trade memory usage for compute time, increasing the required memory to lower the compute time. MIST is able to stitch your data even with low memory, but it will just be slow. The ideal case is when the computer has enough memory to store all image tiles in memory to allow MIST to read each image tile once and only once.</p>
<h4 id="cpu-saturation">CPU Saturation</h4>
<p>If memory is not an issue then the next bottleneck is the CPU.</p>
<p>Modern CPUs often have many cores and it might take several threads of compute work to saturate the CPU. MIST has an advanced parameter that controls how many <strong>CPU Worker Threads</strong> are used. By default this value is set to the number of cores available on the computer in an attempt to saturate the CPU by providing it enough work. Increasing the number of <strong>CPU Worker Threads</strong> beyond the default is strongly discouraged. The number of <strong>CPU Worker Threads</strong> should only be used to artificially throttle the CPU.</p>
<p>If the fully saturated CPU is not providing the performance you require a GPU can be added to accelerate the MIST stitching computation.</p>
<p>One of the MIST <strong>Stitching Program</strong> types is CUDA, which utilizes an NVidia GPU to accelerate the computation. The GPU needs to be CUDA compute capable 2.0 or greater. Also only NVidia GPUs will work as MIST relies on the CUDA toolkit which only works with NVidia GPUs. It is recommended that any GPUs have at least 1GB of graphics memory, but the actual required memory depends on the size of the image grid. For larger grids, 2GB or 4GB of graphics memory might be required. See the question <a href="#mist-encountered-an-out-of-memory-problem">MIST encountered an Out of Memory problem</a>, specifically the <a href="#cuda-mode">CUDA Mode</a> subsection for details on the GPU memory required.</p>
<hr>
<h2 id="i-have-a-gpu-in-my-machine-but-it-is-not-showing-up">I have a GPU in my machine but it is not showing up</h2>
<p>Under the MIST Advanced parameters tab select the CUDA <strong>Stitching Program</strong> type. Press the button labeled <strong>Execute Device Query</strong> to call the CUDA device query and find which GPUs the CUDA system can find connected. If you expect to see a GPU which does not show up, check that you have the proper version of the CUDA toolkit is installed. See <a href="https://github.com/USNISTGOV/MIST/wiki/Install-Guide">CUDA Install Guide</a> for directions on how to install the CUDA toolkit version that is required. If the proper toolkit is installed and the GPU does not show up, the GPU might not have the required compute capability (compute capability of 3.0, Kepler architecture or newer), or it might not operate with CUDA in the manner MIST is expecting. Debugging GPU compatibility is beyond the scope of this FAQ.</p>
<hr>
<h2 id="how-to-stitch-from-metadata">How to stitch from metadata</h2>
<p>To stitch from metadata there must be a previous execution of MIST that generated the metadata the current stitching will use. In the previous run, MIST output several metadata files into the directory indicated by the <strong>Metadata Directory</strong> specified in the Output tab. To setup the new stitching from metadata, enter the new image grid information into the Input tab. Turn the <strong>Assemble From Metadata</strong> checkbox on. This will enable the <strong>Global Positions File</strong> box. Enter into <strong>Global Positions File</strong> the filepath to the global positions metadata file from which you want to stitch. The global positions file file contains the final positions of each individual image tile in the output stitched image and those positions are used to assemble the new images into a mosaic.</p>
<hr>
<h2 id="stitching-time-slices">Stitching Time-Slices</h2>
<p>MIST is designed to stitch 2D image grid datasets. It does not address volumetric or 3D stitching which requires a system to identify and correlate features across a third dimension.</p>
<p>However, MIST has the facility for handling a sequence of independent image grids. This ability to iterate over a series of independent image grids enables both time-lapse stitching, as well as z-stack stitching. Since each stitched image grid is independent, MIST does not care whether it is iterating over time-slices, or z-stacks.</p>
<p>See <a href="#my-image-filename-pattern-does-not-work">My image filename pattern does not work</a> for details on how to setup the <strong>Filename Pattern</strong>.</p>
<p>To control which time-slices are stitched there is a field in the Input tab called <strong>Timeslices</strong> which takes a comma separated list and/or number range to specify the time-slice numbers you want MIST to stitch. For example, the <strong>Timeslices</strong> input could be &quot;1-25,35,45&quot; which would stitch timeslices 1 through 25, 35, and 45.</p>
<p>Any series of independent image grids can be input into MIST as time-slices in order to stitch them.</p>
<hr>
<h2 id="stitching-multiple-channels">Stitching Multiple Channels</h2>
<p>MIST does not currently support the direct stitching of multiple image channels.</p>
<p>However, by taking advantage of the assemble from metadata functionality one can perform the same task. If you have a dataset with two channels that you want to stitch, first select which channel to use for stitching. Setup and run MIST for this channel. To assemble the second channel using the same translations the first channel generated, re-launch MIST. In the input tab update the <strong>Filename Pattern</strong> to reflect the second channel. Select <strong>Assemble From Metadata</strong>. This will enable the <strong>Global Positions File</strong> text box. Enter into the <strong>Global Positions File</strong> box the filepath to the global positions metadata file to use to assemble the new channel.</p>
<p>In the output tab keep the same <strong>Output Directory</strong> and <strong>Metadata Directory</strong>. Change the output filename prefix to something different than what was used for the first channel. Select <strong>Begin Stitching</strong> and MIST will use the global positions file selected by the <strong>Global Positions File</strong> text box to assemble the new channel into a stitched image.</p>
<hr>
<h2 id="stitching-using-a-macro-script">Stitching using a Macro Script</h2>
<p>ImageJ/Fiji has the ability to record and run Macro script to automate tasks. See an <a href="http://fiji.sc/Introduction_into_Macro_Programming">Introduction to Macro Programming</a> for a general overview of macro programming in Fiji.</p>
<p>To create a MIST stitching macro use the macro recorder.</p>
<p>Select &quot;Plugins&quot; &gt;&gt; &quot;Macros&quot; &gt;&gt; &quot;Record&quot;</p>
<p>This will open a window showing the macro script version of any commands you run in Fiji.</p>
<p>Open the MIST plugin and setup the parameters to run your experiment and select &quot;Begin&quot;.</p>
<p>The macro recorder should capture the information required to run MIST from a macro script. The captured command can be copied to a macro script and modified to run MIST from a macro.</p>
<hr>
<h2 id="what-is-stage-repeatability">What is Stage Repeatability</h2>
<p>A motorized mechanical XY-Stage is used to move a biological sample with respect to the microscope’s optical imaging system. This movement is done by two independent stepper motor linear actuators, one for each direction.</p>
<p>It is important to understand the mechanical limitations of a stepper motor linear actuator mainly with regards to its accuracy and repeatability.</p>
<p><em>Accuracy</em>: Actuator motion can only be as true as the mechanical components permit. The accuracy is the actuator’s ability to provide precise increments of motion along its axis. In a mechanical system, this primarily concerns the lead screw as well as the feedback device (encoder, linear scale etc.). Lead accuracy of the screw, resolution of encoders, and ability of the controller must combine to produce the desired accuracy. In most microscopes the accuracy is very high and can be calibrated.</p>
<p><em>Repeatability</em>: Repeatability is the ability of a device to reach a specific location multiple times. It does not take into account the trueness of the position but rather the ability to go back to that position. Many times the actuator will follow a slightly bowed or twisted path due to imperfect construction. The repeatability is the measure of uncertainty relative to a given actuator movement. The repeatability cannot be calibrated, but it can be measured for any microscope stage. Each time the stage controller requests a position value, the actual resulting position is within repeatability of the requested value.</p>
<p>In a grid tiling, the positions (x, y), that the stage will go to, have an uncertainty equal to the stage repeatability (x &plusmn; r, y &plusmn; r). However, translations (dx, dy) computed in the vertical or horizontal directions between consecutive tiles are differences between respective positions. Thus, the uncertainty on the computed translation values is 2*repeatability(dx &plusmn; 2r, dy &plusmn; 2r).</p>
<p>When computing vertical translations between two consecutive tiles, the dx and dy components will correspond to the projection of the stage displacement on the camera coordinate systems (which might have a fixed rotational angle) with an uncertainty equal to 2*repeatability. We use this information to estimate the stage repeatability from the computed translations.</p>
<p>The <strong>Stage Repeatability</strong> value can be entered into MIST under the advanced parameters tab of the GUI. MIST expects a <strong>Stage Repeatability</strong> values in pixels.</p>
<hr>
<h2 id="submitting-issue-or-bug-report">Submitting issue or bug report</h2>
<p>The code for MIST is being stored and managed on Github which has the functionality to report and track issues. To report a bug go to the <a href="https://github.com/USNISTGOV/MIST">MIST Github page</a> and select &quot;Issues&quot; on the right hand side of the page. Or go directly to the <a href="https://github.com/USNISTGOV/MIST/issues">Issues page</a>. To create a new issue select the green &quot;New Issue&quot; button on the top right side of the page.</p>
<p>When posting in issue please be as specific as you can and if possible include the following data generated by MIST from the stitching experiment that encountered the error.</p>
<ol>
<li>The contents of the Log window in Fiji.<ul>
<li>done by clicking the menu option &quot;File&quot; &gt;&gt; &quot;Save As&quot; on the Log window</li>
</ul>
</li>
<li>The relevant metadata files<ul>
<li>statistics file (important)</li>
<li>global positions file</li>
<li>relative positions file</li>
<li>relative positions no optimization file</li>
</ul>
</li>
</ol>
<p>If you have questions or issues regarding MIST feel free to email the developers at: nist-mist@nist.gov</p></body>
</html>
